<!-- ##### SECTION Long_Description ##### -->
<para>
-GtkBinding provides a mechanism for configuring Gtk+ key bindings through RC files.
-This eases key binding adjustments for application developers as well as users and
-provides Gtk+ users or administrators with high key binding configurability which
-requires no application or toolkit side changes.
+GtkBinding provides a mechanism for configuring GTK+ key bindings through
+RC files. This eases key binding adjustments for application developers as
+well as users and provides GTK+ users or administrators with high key
+binding configurability which requires no application or toolkit side changes.
</para>
<refsect2>
<title>Installing a key binding</title>
<para>
-A resource file binding consists of a 'binding' definition and a match statement to
-apply the binding to specific widget types. Details on the matching mechanism are
-described under <link linkend="gtkrc-pathnames-and-patterns">Pathnames and patterns</link>.
-Inside the binding definition, key combinations are bound to specific signal emissions
-on the target widget. Key combinations are strings consisting of an optional #GdkModifierType
-name and <link linkend="gdk-Keyboard-Handling">key names</link> such as those defined in
-<filename><gdk/gdkkeysyms.h></filename> or returned from gdk_keyval_name(), they have
-to be parsable by gtk_accelerator_parse().
-Specifications of signal emissions consist of a string identifying the signal name, and
-a list of signal specific arguments in parenthesis.
-
-For example for binding Control and the left or right cursor keys of a #GtkEntry widget to the
-#GtkEntry::move-cursor signal, so movement occurs in 3 letter steps,
-the following binding can be used:
+A resource file binding consists of a 'binding' definition and a match
+statement to apply the binding to specific widget types. Details on the
+matching mechanism are described under
+<link linkend="gtkrc-pathnames-and-patterns">Pathnames and patterns</link>.
+Inside the binding definition, key combinations are bound to specific signal
+emissions on the target widget. Key combinations are strings consisting of
+an optional #GdkModifierType name and
+<link linkend="gdk-Keyboard-Handling">key names</link> such as those defined
+in <filename><gdk/gdkkeysyms.h></filename> or returned from
+gdk_keyval_name(), they have to be parsable by gtk_accelerator_parse().
+Specifications of signal emissions consist of a string identifying the signal
+name, and a list of signal specific arguments in parenthesis.
+</para>
+<para>
+For example for binding Control and the left or right cursor keys of a
+#GtkEntry widget to the #GtkEntry::move-cursor signal, so movement occurs
+in 3 letter steps, the following binding can be used:
<informalexample><programlisting>
binding "MoveCursor3" {
<anchor id="gtk-bindings-unbind"/>
<title>Unbinding existing key bindings</title>
<para>
-Gtk+ already defines a number of useful bindings for the widgets it provides.
-Because custom bindings set up in RC files take precedence over the default bindings
-shipped with Gtk+, overriding existing bindings as demonstrated in
+GTK+ already defines a number of useful bindings for the widgets it provides.
+Because custom bindings set up in RC files take precedence over the default
+bindings shipped with GTK+, overriding existing bindings as demonstrated in
<link linkend="gtk-bindings-install">Installing a key binding</link>
-works as expected. The same mechanism can not be used to "unbind" existing bindings,
-however.
+works as expected. The same mechanism can not be used to "unbind" existing
+bindings, however.
<informalexample><programlisting>
binding "MoveCursor3" {
class "GtkEntry" binding "MoveCursor3"
</programlisting></informalexample>
-The above example will not have the desired effect of causing "<Control>Right"
-and "<Control>Left" key presses to be ignored by Gtk+. Instead, it just causes
-any existing bindings from the bindings set "MoveCursor3" to be deleted, so when
-"<Control>Right" or "<Control>Left" are pressed, no binding for these keys
-is found in binding set "MoveCursor3". Gtk+ will thus continue to search for matching
-key bindings, and will eventually lookup and find the default Gtk+ bindings for entries
-which implement word movement. To keep Gtk+ from activating its default bindings, the
-"unbind" keyword can be used like this:
+The above example will not have the desired effect of causing
+"<Control>Right" and "<Control>Left" key presses to be ignored
+by GTK+. Instead, it just causes any existing bindings from the bindings
+set "MoveCursor3" to be deleted, so when "<Control>Right" or
+"<Control>Left" are pressed, no binding for these keys is found in
+binding set "MoveCursor3". GTK+ will thus continue to search for matching
+key bindings, and will eventually lookup and find the default GTK+ bindings
+for entries which implement word movement. To keep GTK+ from activating its
+default bindings, the "unbind" keyword can be used like this:
<informalexample><programlisting>
binding "MoveCursor3" {
class "GtkEntry" binding "MoveCursor3"
</programlisting></informalexample>
-Now, Gtk+ will find a match when looking up "<Control>Right" and "<Control>Left"
-key presses before it resorts to its default bindings, and the match instructs it to abort
-("unbind") the search, so the key presses are not consumed by this widget.
-As usual, further processing of the key presses, e.g. by an entries parent widget,
-is now possible.
+Now, GTK+ will find a match when looking up "<Control>Right" and
+"<Control>Left" key presses before it resorts to its default
+bindings, and the match instructs it to abort ("unbind") the search, so
+the key presses are not consumed by this widget. As usual, further processing
+of the key presses, e.g. by an entry's parent widget, is now possible.
+</para>
+<para>
+The "unbind" functionality has been introduced in GTK+ 2.12.
</para>
</refsect2>
<varlistentry>
<term><link linkend="Resource-Files">Resource Files</link>
</term>
-<listitem><para>Gtk+ Resource Files - behavior and style definitions.</para></listitem>
+<listitem><para>GTK+ Resource Files - behavior and style definitions.</para></listitem>
</varlistentry>
</variablelist>
<para>
A binding set maintains a list of activatable key bindings.
A single binding set can match multiple types of widgets.
-Similar to styles, widgets can be mapped by widget name paths, widget class paths or widget class types.
-When a binding within a set is matched upon activation, an action signal is emitted on
-the target widget to carry out the actual activation.
+Similar to styles, widgets can be mapped by widget name paths, widget
+class paths or widget class types. When a binding within a set is
+matched upon activation, an action signal is emitted on the target
+widget to carry out the actual activation.
</para>
@set_name: unique binding set name
<!-- ##### STRUCT GtkBindingEntry ##### -->
<para>
-Each key binding element of a binding sets binding list is represented by a #GtkBindingEntry.
+Each key binding element of a binding sets binding list is represented by
+a #GtkBindingEntry.
</para>
@keyval: key value to match
@binding_set: binding set this entry belongs to
@destroyed: implementation detail
@in_emission: implementation detail
-@marks_unbound:
+@marks_unbound: implementation detail
@set_next: linked list of entries maintained by binding set
@hash_next: implementation detail
@signals: action signals of this entry
projects / gtk4.git / commitdiff